Skip to content

Conversation

@bobsira
Copy link
Owner

@bobsira bobsira commented Jan 2, 2025

Testing Instructions for this PR

🛠 Prerequisites (Local Machine)

Local Repositories

Environment & Tools

  • Windows Host: Hyper-V must be available and enabled.
  • Elevated PowerShell: Must run as Administrator for cluster creation.
  • Git Bash: Recommended for building minikube via make.
  • Go Toolchain: Ensure a standard development environment with all minikube build dependencies is installed.

1) Build Minikube

From the root of the minikube repository:
Run from Git Bash:
make


2) Start a Hybrid Cluster (Elevated PowerShell Required)

Important

⚠️ Important: This step must be run from an elevated (Administrator) PowerShell session. Failure to do so will result in permission errors during Hyper-V VM creation.

From the root of the repository, run:

Basic Usage (Built-in Windows VHD)
.\minikube.exe start --kubernetes-version=v1.32.3 -n 2 --node-os='[linux,windows]'

What this does:

  • Provisions two nodes:
    • A Linux control plane VM
    • A Windows worker VM
  • Configures the environment:
    • Uses the default Windows Server VHD bundled/configured by Minikube.
    • Boots the Windows VM via Hyper-V.
  • Initializes Kubernetes:
    • Installs required Kubernetes components on the Windows node.
    • Automatically joins the Windows node to the cluster.
    • Applies correct OS labels and taints.

🛠 Using a Custom Windows VHD

The --windows-vhd-url flag allows you to supply your own Windows Server VHDX image. This can be either:

  • A remote URL (e.g., Azure Blob Storage)
  • A local absolute path

Note

The VHD must already contain:

  • Windows Server
  • Container runtime
  • Kubernetes node prerequisites

Remote
.\minikube.exe start --kubernetes-version=v1.32.3 -n 2 --node-os='[linux,windows]' --windows-vhd-url='https://<your-storage>/hybrid-minikube-windows-server.vhdx'

Local path
.\minikube.exe start --kubernetes-version=v1.32.3 -n 2 --node-os='[linux,windows]' --windows-vhd-url='C:\vhd\hybrid-minikube-windows-server.vhdx'

Minikube will:

  • Attach the specified VHD to the Windows VM.
  • Boot directly from the image.
  • Skip OS installation steps.
  • Proceed directly to Kubernetes node bootstrap and join.

3) Verify Cluster State

Once minikube start completes:

  • kubectl get nodes -o wide should show two nodes with OS labels: one linux, one windows.

Setting up the cluster
minikube_pic

Verify your cluster
cluster

@bobsira bobsira requested a review from Copilot January 2, 2025 12:14
Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot reviewed 5 out of 10 changed files in this pull request and generated 6 comments.

Files not reviewed (5)
  • pkg/minikube/bootstrapper/bootstrapper.go: Evaluated as low risk
  • pkg/minikube/config/types.go: Evaluated as low risk
  • pkg/minikube/constants/constants.go: Evaluated as low risk
  • pkg/minikube/bootstrapper/certs.go: Evaluated as low risk
  • pkg/minikube/machine/client.go: Evaluated as low risk
Comments suppressed due to low confidence (4)

pkg/minikube/node/powershell.go:21

  • The variable 'powershell' should be checked to ensure it is not empty after 'exec.LookPath'. If 'powershell' is not found, an error should be returned.
powershell, _ = exec.LookPath("powershell.exe")

pkg/minikube/node/powershell.go:35

  • [nitpick] The function 'cmdOut' should return stderr in case of an error to make debugging easier.
return stdout.String(), err

pkg/minikube/node/start.go:1073

  • [nitpick] The error message could be more descriptive. Consider providing more context about the command that failed.
klog.Infof("couldn't run %q command. error: %v", rr.Command(), err)

pkg/minikube/node/start.go:389

  • The new behavior for Windows nodes should be covered by tests to ensure it works as expected.
joinCmd, err = cpBs.GenerateTokenWindows(*starter.Cfg)

@bobsira bobsira changed the title Windows Node Setup [minikube]:windows node setup Feb 27, 2025
@TinaMor
Copy link

TinaMor commented Mar 18, 2025

@bobsira Tested this locally and it works fine.

nit: Checked the minikube start --help. Is this correct? --windows-node-version='2025': and Defaults to Windows Server 2022

--windows-node-version='2025':
        The version of Windows to use for the Windows node on a multi-node cluster (e.g., 2019, 2022). Defaults to Windows Server 2022

@kartikjoshi21
Copy link

@bobsira Thankyou for the PR, I tested it on windows machine , It looks good to me, im able to spawn 2 different minikube nodes one with buildroot and other with windows server 2025.

Copy link

@TinaMor TinaMor left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

Copy link

@ShemManyu ShemManyu left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@mloskot
Copy link

mloskot commented Dec 15, 2025

Any updates on this?

@bobsira
Copy link
Owner Author

bobsira commented Dec 16, 2025

Any updates on this?

Hello @mloskot — we are targeting inclusion of this functionality in the next Minikube release.

For context, the Minikube maintainers are currently consolidating the minikube-machine repository into the main minikube repository. As a result, the changes implemented in this PR will need to be migrated into the Minikube repo once that consolidation is complete.

The expectation is that this consolidation will be finalized ahead of the next release, allowing the work to be carried over without blocking the release timeline.

@mloskot
Copy link

mloskot commented Dec 16, 2025

@bobsira Thank you very much for the update and for the hard work you've done her!

@bobsira bobsira force-pushed the feature/windows-node-support branch from 528d214 to 92e53aa Compare January 12, 2026 14:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

9 participants